Q-emuLator Lite is a freeware and reduced version of the commercial QL software emulator for the MacOS.
Q-emuLator emulates the QL's processor (the Motorola M68008) and redirects the basic QL I/O (video, keyboard, mass storage, sound, serial ports) to the Macintosh hardware.
Q-emuLator runs like any other applications in the MacOS environment, without taking over all the machine.
How to install Q-emuLator Lite
Q-emuLator requires that you put a QL ROM image in the same folder as the application, before you can start an emulation session.
The process of copying the ROM image from a QL is fully described in the 'How to install Q-emuLator Lite' document (in this folder).
Differences between Q-emuLator Lite and the commercial version
The main difference between Q-emuLator and Q-emuLator Lite is SPEED: the Lite version is limited to about 25% of the QL's speed, while the commercial version runs at about the same speed as a QL on a Macintosh LC630, and proportionally slower on other models (for example, with a 25MHz 68040 the speed is about 85%).
To appreciate the difference in speed between Q-emuLator Lite and the commercial version of Q-emuLator try to execute the demonstrative QL program (in the 'QL demo software' folder, contained in the 'About commercial Q-emuLator…' folder) first with the Lite program and then with Q-emuLator DEMO (in the 'About commercial Q-emuLator…' folder), which is roughly as fast as the commercial program.
Some features are available only in the commercial version of Q-emuLator, and not in the Lite version:
- full emulation speed
- emulation of QL's sound
- accelerated text output, scroll, pan and cls
- accelerated loading of SuperBasic programs (for all rom versions but the Minerva)
- up to 4M of QL RAM
- it is possible to add a second external ROM in the virtual QL's external expansion slot
- support for the NTSC display mode
- a Display menu, to redraw the display and choose between the proportional view and the reduced view, where pixel's doubling is inhibited
- some minor features, like the possibility of installing a ROM by double clicking on its icon in the Finder
- you can associate with your files a special piece of information so that the copy-protection scheme used in some programs supplied on microdrive cartridges continues to work
- preferences are automatically saved when changed
Q-emuLator Lite doesn't save the preferences; if you use some preferences different from the default ones, you'll have to change them again every time you start Q-emuLator Lite. The possibility of changing the preferences at runtime is nevertheless provided so that you can try the various options (like adding a ROM in the virtual back slot) and verify their working.
Finally, Q-emuLator Lite displays a dialog when the application starts. The dialog is not present in the commercial version.
IMPORTANT: There is also a feature found only in Q-emuLator Lite and not present in the commercial release: better support for B&W displays. This feature was discontinued (maybe it will be reintroduced in future upgrades), and in the commercial version the B&W display is almost unreadable, as the conversion from color to B&W is performed by the MacOS rather than by custom routines. You SHOULDN'T buy the commercial version of Q-emuLator if you don't have a color monitor.
Compatibility with the MacOS
Q-emuLator has been tested on many Macintosh models, and the best performance has been achieved on the LC630. Q-emuLator runs rather slowly on Power Macintosh; after all, it's an emulator running under emulation… There will likely be a native version in the future.
Minimum Q-emuLator Lite system requirements:
- System 6.0.7
- 2M of RAM
Note: The commercial version has slightly more demanding requirements. See the 'How to order Q-emuLator' document (in the 'About commercial Q-emuLator…' folder).
IMPORTANT: To install any version of Q-emuLator or Q-emuLator Lite your Macintosh must be able to read QL-formatted disks; otherwise you can't transfer the ROM from your QL to the Macintosh. This is possible only with a Macintosh equipped with the SuperDrive; all Macintosh but the oldest have it; in particular the Mac Plus, the early SE and the original Mac II don't have the SuperDrive, so you can't use Q-emuLator with them. For the same reason you must own a QL with a 3.5" floppy disk drive.
Compatibility with the QL
Q-emuLator emulates a standard QL almost without compatibility problems. 'Standard QL' means one of the machines produced by Sinclair. All the Sinclair's ROMs are supported but the very first ones (those which had only 32K inside the QL and the remaining 16K inserted in the back ROM slot).
Q-emuLator should work with any Sinclair ROM from version 'AH' to the various 'MG' versions. The Minerva rom is supported as well, although only version 1.97 has been tested so far.
Q-emuLator doesn't work with SMSQ.
Over one hundred QL programs have been tested with Q-emuLator and compatibility is very good. All seem to work but a few games which are buggy, although their bugs cause problems only with the emulator and not with a true QL.
About 98% of the tested programs work well with Q-emuLator.
Ram
Q-emuLator Lite takes about 1.5M of RAM. You can reduce this amount in the Finder's 'Get Info' dialog box. The minimum amount of RAM required to emulate a QL with X kilobytes of RAM, is 850+X kilobytes. Thus a standard 128K QL requires setting the Q-emuLator RAM amount (minimum and preferred size, in the 'Get Info' dialog box) to 978K, while with 1234K you may have a QL with 384K of RAM. With the commercial version of Q-emuLator you can have a virtual QL with up to 4M of RAM; the Lite version is limited to 640K.
Sometimes the virtual QL can have more RAM than the above rule would suggest: the extra memory is taken from the video emulation and the result is that the display will be only black and white. This feature was added to support systems with really scarce memory.
Menus
This paragraph briefly describes the menus which are specific to Q-emuLator.
File menu
'Install QL rom' installs the QL ROM from a QL-formatted floppy disk, as explained in the How to install Q-emuLator Lite document.
'Eject' ejects a QL-formatted floppy disk. The command is dimmed when the drive is empty or the inserted disk is not in QL format.
'Format QL disk…' initialises a floppy disk in QL format. After selecting this command from the menu, insert in the drive the disk that you want to initialise.
Note: Floppy disks which are already in QL format should be re-formatted using the 'FORMAT' command from SuperBasic, not with the Format QL disk… command.
Note: Before using the Format QL disk… command, the disk drive should be empty, because the command doesn't allow to eject disks from the drive. If there is a disk in the drive you should eject it before selecting the command: if the disk is in QL format you can use the 'Eject' command in the File menu; if it is a Macintosh disk, switch to the Finder and drag the disk icon into the trash.
QL menu
'Start' starts a QL emulation session. When the emulated QL is running, 'Restart' is the same as pressing the reset button on the right side of a QL.
'Stop' stops the emulation session, switching off the emulated QL. Most configuration options (like the amount of QL's RAM) can be changed only when the emulated QL is not running.
The 'Fast startup' option permits skipping the initial RAM checking by the QL during the start-up phase. If you want to try to uncheck the option, be sure to set the QL RAM to its minimum (128K), otherwise the RAM checking will take quite a long time.
'Turn sound on/off' toggles the sound emulation on or off. This command is disabled in the Lite version, as sound emulation is available only in the commercial package.
'QL Configuration…' displays the dialog which allows you to set the QL configuration and the Q-emuLator preferences. The configuration dialog is described in the 'The QL configuration dialog' chapter in this document.
Keyboard menu
There are three ways to accomplish keyboard emulation:
'Raw mode' establishes a correspondence between physical keys on the QL's and Mac's keyboards. This works only if the two keyboards have the same layout. For example it should work if you have the original (not localised) QL keyboard and a U.S. Mac keyboard, but not if you have the original QL keyboard and a French Mac keyboard.
'QL mode' is the preferred mode. It automatically makes adjustments to account for the different QL and Macintosh keyboard layouts.
'Mac mode' translates Mac characters to QL characters. The main difference between this and the previous mode is the treatment of the option key: while in QL mode option+key generates an alt code (255) followed by the code of the key, in Mac mode option+key generates a single key, the same as in the normal Macintosh environment. For example, option+p generates the π character. The 'Key Caps' standard desk accessory shows the correspondence between keys and characters. Note that in Mac mode the alt+key combinations (required by many programs and utilities) don't work, because they don't produce the required two-code sequence.
Note: Many programs (mostly games) read the keyboard directly instead of looking at the characters generated from it. These programs always read the keys' positions (raw mode), regardless of the mode which is selected.
RAM menu
In this menu you can set the RAM amount for the emulated QL. The menu is disabled when the emulated QL is running.
RAM sizes too large for the current Q-emuLator memory partition are disabled. To enable them, increase the Q-emuLator RAM through the Finder's 'Get Info' dialog box.
Note: Some old QL's programs don't work unless the RAM is set to 128K.
'Back ROM' enables (when it is checked) the 16K ROM virtually inserted in the QL's back ROM slot. Before activating this option, you should install the back ROM using the 'QL Configuration…' dialog.
Frequency menu
You can set the interrupt frequency to '50Hz' or '60Hz'. Most QLs have 50Hz interrupt's frequency. In Macintosh models which don't have the 68040 processor (including Power Macs) there's also a '10Hz' option ('5Hz' for 68000 Macs), which should be selected to avoid a severe slow down of the emulation; otherwise the QL interrupt routines take over most of the emulation time, leaving only a small amount to do something useful.
Windows menu
Through this menu you can activate the two Q-emuLator windows: 'Display' and 'Microdrives'.
Note: Most of the options selected through the menus are automatically saved by Q-emuLator, so the set-up will be the same the next time you will use the emulator. The preferences are NOT saved in the Lite version, and a dialog is displayed instead, explaining that this feature is not available.
Useful keys
The delete key deletes the last character: it is the same as Ctrl+Left Arrow.
The ALT key, absent on Macintosh keyboards, is replaced by the Option key.
Some Macs don't have function keys. They can be obtained by pressing Command+number.
Disks and files
The 'Microdrives' window has two slots of a virtual device, accessible from the QL with the MDV and/or FLP and/or WIN device. In this way all programs should work regardless of the particular device they use. Each virtual slot can be mapped onto a physical device, which can be either a directory of the Mac file system (on hard disk, floppy, CD-ROM, etc.) or a QL-formatted floppy disk.
The led on the left of each slot lights when the device is being accessed.
To associate a slot with a Mac's directory:
click on the slot and select a file contained in the directory in the standard file dialog that will appear.
To associate a slot with a QL-formatted disk:
insert the QL-formatted disk while the Q-emuLator application is active and choose the destination slot from the dialog which will appear.
To leave a slot empty:
click on the slot and select the Cancel button in the standard file dialog.
Note: The Cancel button doesn't cancel the operation; it means 'leave the slot empty'.
To eject a QL-formatted disk:
choose the 'Eject' command from the File menu (or click on the slot and select the Cancel button).
To reformat a QL-formatted disk:
associate the disk with a slot and use the SuperBasic FORMAT command.
Note: The format command works only for QL-formatted floppy disks, while for Mac directories it does nothing, apart from setting the slot name (but the real directory name remains unchanged). So you don't risk erasing your hard disk!
To format an uninitialised disk:
insert the disk while the Q-emuLator application is active and select the desired format (QL or Mac). You can also use the 'Format QL disk…' command in the File menu, which works even if the disk is already initialised.
Note: If the disk is a Mac-formatted disk (or DOS-formatted and you have AccessPC or similar utilities installed), when you insert it in the drive it will be mounted in the Mac file system, unless you are in the 'Format QL disk…' dialog box.
To format an initialised Mac disk in QL format:
use the 'Format QL disk…' command in the File menu, then insert the disk in the drive.
Note: If the disk is already in QL format, Q-emuLator asks to you to put the disk in one of the FLP slots, instead of formatting the disk. To format such a disk you should use the 'FORMAT' command from SuperBasic.
When the emulator creates QL files in a Mac directory, it puts the QDOS file header in the resource fork, to save information like the data space for executable programs.
IMPORTANT: With some old QL floppy disks, Q-emuLator could be unable to read any data, complaining about a 'cannot locate sector' error. This is likely due to slight differences between old QL disk drives and the Macintosh SuperDrive, which makes some disks unreadable. This is a hardware problem, not a Q-emuLator's fault!
Video and speed
Q-emuLator Lite video emulation works both in color and B&W. Here is the behaviour for the various pixel depths:
- 1 bit/2 colors: B&W
- 2 bit/4 colors: mode 8 is B&W and mode 4 is color
- 4 bit/16 colors: color
- 8 bit/256 colors: color. This is the preferred pixel's depth
- 16 or 32 bit: color
B&W mode:
bright colors become white, dark colors become black, mid-brightness colors are rendered as a black and white stripes pattern. Only four colors can be distinguished, so in mode 8 some colors look the same (for example blue becomes black).
To speed up emulation on old Macintosh models like the Classic, some graphic operations are much optimized in B&W mode (for all rom versions but the Minerva). This doesn't happen in color mode, unless you have the commercial version, which has optimized graphic commands for all the supported rom versions.
Screen updates and speed:
if your monitor is set to 256 colors and the QL display window is completely visible, then the screen is updated writing directly to the video memory. Always use this mode!
Otherwise (monitor depth other than 8 bit, or window partially covered or out of the screen) the screen is updated through Mac Toolbox calls (this happens in B&W mode, too). This result in MUCH slower updates. In this way updates become also inexact: to preserve the correct QL's pixel ratio some pixel rows are doubled in the Mac window. This causes (I'm not going to explain the exact reason, because it would take too long, but this happens because updates are only local and don't extend to the whole screen each time) a weird behaviour where using the Mac Toolbox the pixel rows can be drawn each time at slightly different vertical coordinates (±1 pixel).
If the Check screen depth option is checked in the 'QL configuration…' dialog, every time you start a QL emulation session Q-emuLator checks for the optimal screen setting and offers to change it for you if it is not already set.
Serial ports
SER1 is the printer port and SER2 the modem port.
You can change this mapping through the 'QL Configuration…' dialog.
The QL configuration dialog
The 'QL Configuration' dialog allows the setting of the emulated QL's configuration and of the Q-emuLator's preferences.
The upper part of the window displays four icons, one for each configuration page: Memory, Files, Serial ports, Miscellaneous
Clicking on an icon displays the corresponding page in the lower part of the window. Initially the active page is the memory page.
Memory:
in this page you can set the emulated QL's ram amount (you can set it also through the RAM menu) and select which ROMs to install. You can type the ROM name directly or you can use the 'Select…' button, which allows you to select the file. ROM files must be 48K long for the main ROM and 16K long for the back ROM. The file must be in the same folder as the Q-emuLator application. If the selected file is not a Q-emuLator's file, the file's type and creator are changed, so that it will appear with the proper icon in the Finder's windows. The back ROM is actually installed only if the 'Active' switch is checked. The switch can also be controlled with the Back ROM option in the RAM menu.
Note: To copy a ROM image from your QL's back slot to the Q-emuLator folder:
1) copy the ROM to a QL-formatted floppy disk, with the command 'SBYTES flp1_ROM_NAME, 49152, 16384';
2) in Q-emuLator, link the Q-emuLator folder to the left slot, and insert the floppy disk containing the ROM image in FLP2. Copy the image with the 'COPY flp2_ROM_NAME to flp1_ROM_NAME';
3) you can now install the ROM by pressing the 'Select…' button in the 'QL Configuration' dialog.
Files:
you can change the name of the floppy disk and hard disk device drivers, or you can disable the driver installation. Regardless of their name, all file devices are able to access both the virtual slots, even if the attached medium is of another kind.
Serial ports:
it is possible to route the SER1 and SER2 QL's serial devices to the printer port, to the modem port, or to nothing. In the latter case the SER device can't be used. Both SER1 and SER2 can be routed to the same Mac's port, provided they are not used simultaneously. If, when opening the device, it is found already in use by Q-emuLator, by another program, or by AppleTalk, the open fails returning an 'IN USE' error.
Miscellaneous:
'Skip QL memory check during reset' is the same as the 'Fast startup' option in the QL menu. When the option is checked, QDOS skips the long memory check phase when starting or restarting the QL.
'Open QL session at startup' makes Q-emuLator to automatically execute a 'Start' command whenever the Q-emulator application is launched. In the Lite version it doesn't make sense to check the option, as preferences are not saved.
'Sound emulation' is the same as the 'Turn sound on/off' switch in the QL menu. It toggles sound emulation on or off. It has effect only in the commercial version of Q-emuLator.
'Check screen depth' makes Q-emuLator to check for the optimal screen depth (256 colors) every time a QL emulation session starts.
How to contact the Q-emuLator's author
Feel free to contact the author for any matter concerning the emulator (bugs, suggestions, comments, etc.). You can find the addresses (physical and electronic) in the 'How to order Q-emuLator 1.0' document (in the 'About commercial Q-emuLator…' folder).
